Tema 06 - Introducción a Quarto

El sistema de publicaciones Quarto

• Instalar Quarto para vuestro sistema operativo desde aquí

• La guía y referencia completa de Quarto están en su Web

• Un documento de Quarto se renderiza, procesando cada componente (código, resultado de ejecutarlo y texto) para producir documentos en varios formatos: html, PDF, Word, presentaciones, etc.

Documentos de Quarto: Crear y Guardar

• Un documento de Quarto se crea a partir de una plantilla en RStudio con o File > New File > Quarto Document

  • Podemos elegir Título, Autor/a y formato de salida (HTML, por defecto)

• Se guarda con o con File > Save, con extensión .qmd

• Se renderiza con al formato de salida elegido

• En el botón de engranaje se pueden cambiar algunas opciones

  • p.e., dónde se visualiza la salida (en ventana aparte o en RStudio)

Documentos de Quarto: formato de salida

• El renderizado crea un archivo en el mismo directorio donde está el archivo de Quarto .qmd

• En el caso de HTML, se crea tanto un archivo con extensión .html como un subdirectorio del mismo nombre con componentes necesarios (ej., imágenes, css)

  • solo podemos visualizar correctamente el archivo .html en cualquier navegador si copiamos a otro lugar tanto el .html como el subdirectorio

• Para crear PDFs, se necesita una distribución de LaTeX: instala una escribiendo en la pestaña de “Terminal” (a la derecha de la consola):

quarto install tool tinytex

Documentos de Quarto: Texto con Markdown

• Los componentes de texto están escritos en Markdown: un conjunto ligero de convenciones para archivos de texto sin formato. Por ejemplo,

  • todo lo escrito entre dos * como **Hola** se renderiza en negritas

  • se utiliza # para indicar encabezados de secciones

• En el menú de ayuda tenemos una descripción completa (Markdown quick reference) y “chuletas” (Cheatsheets)

• También son útiles la web de Quarto y este libro online.

• RStudio incorpora un editor visual de documentos de Quarto, similar a un procesador de texto

Editor Visual de Quarto en RStudio

• En documentos .qmd, se puede elegir entre editar la fuente (source) de Markdown, como texto sencillo, o editar el documento de forma Visual en

• En el modo visual, en esa misma barra de herramientas se tienen accesos a

  • formatos de texto (negritas, cursivas, encabezamientos) y listas
  • insertar enlaces, imágenes, notas a pie de página, tablas
  • incluir ecuaciones (en LaTeX)
  • también insertar directamente código HTML, comentarios, etc.

• Se puede configurar la corrección ortográfica en Tools > Global Options > Spelling: agregar/seleccionar el diccionario de Español

Formato en la cabecera: el bloque YAML

• Al principio del documento, entre dos líneas con ---, se pueden especificar varias opciones del documento: título, autor, fecha, formato de salida

• Los formatos de salida son html, pdf, docx (y otros en Quarto Presentations)

• También se especifican opciones globales del documento, algunas específicas de cada tipo de salida (ver la referencia para html y otros formatos)

    ---
    title: "Título"
    author: Autor 
    date: 15-octubre-2023
    format:
      html:
        toc: true              # índice
        number-sections: true  # secciones numeradas
        embed-resources: true  # archivo html autocontenido
        theme: united          # más temas: https://bootswatch.com/3/
    ---

Fragmentos o celdas de código

• Insertamos código en medio del texto con el icono (visual)

• Si pulsamos , escribimos r y luego un código, el documento de salida incluirá el resultado de ejecutar el código

Opciones para una celda de código

• Las opciones se incluyen al principio de una celda precedidas por #|

• Se muestra el código en la salida con la opción echo: true (o no con echo: false)

• Con la opción eval: false, el código se ejecuta: los resultados de ejecutarlo están disponibles y pueden mostrarse (o no con eval: false)

  • Si un fragmento no se evalua, sus resultados no están para otras celdas posteriores (p.e., cargamos datos o una biblioteca para usar luego)

• Incluimos los resultados del código con output: true

• También se pueden mostrar (o no) los mensajes, errores y avisos de ejecutar un código con las opciones message, error y warning, respectivamente.

• La lista completa de opciones aquí

Opciones para una celda de código (cont.)

• Cómo mostrar resultado

  • results: hide (no mostrar)
  • results: hold (mostrar todo, no el resultado de cada línea)

• include: false no incluye ni el código ni su resultado, pero se evalúa

• label: etiqueta para identificar la celda

• code-fold: true oculta el código pero da opción a mostrarlo

• fig-cap y tbl-cap para los títulos

• Cómo mostrar los gráficos: fig-show

  • las opciones hide y hold son como en results
  • animate concatena varios gráficos en una animación

Opciones para una celda de código (y 3)

• fig-width y fig-height: dimensiones (reales, en pulgadas) de una figura

• out-width y out-height: ídem en el documento de salida (% de las reales)

• fig-align: mostrar la figura centrada o alineada a derecha o izquierda

• layout-ncol: en cuantas columnas se componen los resultados

ggplot(data = cars) + geom_histogram(aes(x = speed))  # en la izquierda
ggplot(data = cars) + geom_histogram(aes(x = dist))   # en la derecha

Opciones globales para todas las celdas

• Si no se da un valor a las opciones en una celda, se usa el valor por defecto de Quarto o el definido globalmente en la cabecera.

• En la cabecera, se pueden especificar las opciones de ejecución de código echo, eval, include, output, error, etc. en execute (ver aquí y aquí)

    ---
    execute:
      echo: false
      warning: false
    ---

• También se pueden fijar en la cabecera muchas otras opciones, incluidas algunas que ya hemos visto (un listado completo aquí para html)

Opciones por defecto para todas las celdas (cont.)

    ---
    format:
      html:
        code-fold: true
        cap-location: bottom
        fig-align: center
        df-print: paged
    ---

• La opción df-print especifica el método para visualizar tablas

• También se pueden especificar algunas de estas opciones a través del renderizador de R knitr (descripción completa aquí).

Ejecución de código en un documento .qmd

• Al renderizar un documento .qmd, se crea un nuevo espacio de trabajo y se ejecuta el código allí.

  • ese espacio de trabajo es distinto del que vemos en RStudio: diferentes objetos, incluyendo bibliotecas

  • el directorio de trabajo también es diferente: es el directorio donde se encuentra el .qmd

• Es importante conocer si el código del documento .qmd ofrece los resultados deseado antes de renderizar.

• Cuando tenemos varias celdas de código, algunas pueden depender de cálculos y objetos previos (datos, bibliotecas, resultados)

• Se puede probar ejecutando el código del documento .qmd (sin renderizar): línea a línea, la celda completa con o todas las anteriores con

Ejecución de código en un .qmd (cont.)

• Cuando ejecutamos el código sin renderizar, éste pasa pasa a la consola y sí forma parte del espacio de trabajo de la sesión actual de R.

• Debemos asegurarnos de que la sesión actual incluye sólo resultados del código de celdas del documento para que nuestra prueba sea equivalente a lo que obtendríamos renderizando

• Resulta útil incluir una celda código al principio del documento (que se evalúe pero no muestre código ni resultados) que incluya

  • rm(list = ls()): al ejecutar todas las celdas previas, empezamos con una sesión sin objetos y podemos probar el código de la celda actual

  • Todas las bibliotecas (ej., tidyverse) que utilizaremos en varias celdas

  • Fijar el directorio de trabajo para acceder a archivos (p.e., imágenes, datos). Esto es innecesario si hemos sido cuidadosos y creado el archivo .qmd como parte de un proyecto.

Mejorar la salida de tablas

• Los resultados de muchas funciones de R no son visualmente “profesionales” en el documento de salida de .qmd

• Varias bibliotecas cambian algunas salidas por defecto (printr) u ofrecen funciones para mejorarlas (pander::pandoc.table(), xtable::xtable())

• Por ahora, veremos la función kable() de la biblioteca knitr

• Más adelante veremos la biblioteca kableExtra, con más opciones.

  • kableExtra muestra “data frame”/“tibbles” como tablas

  • broom::tidy() (de tidyverse) convierte mucho objetos de R (como listas con resultados de comandos) en tibbles

• Otras bibliotecas similares: modelsummary, stargazer

Comentarios finales: Dashboards (Tableros)

• Los dashboards son un tipo de interfaz gráfica para los usuarios finales que ofrecen visualizaciones rápidas de indicadores o resultados clave

• Estas presentaciones visuales e interactivas de los resultados de un análisis de datos puede ayudar a una comunicación más efectiva

• Con Quarto se pueden crear varios tipos de dashboards interactivos, aunque no vamos a profundizar en ellos

• En particular, Quarto trabaja con el paquete de R llamado Shiny que permite crear fácilmente aplicaciones web interactivas

• Podéis encontrar ejemplos de las capacidades de Shiny en esta galería de aplicaciones

Comentarios finales: libros de notas Jupyter

• Son otra forma de combinar texto, código y resultados en un documento

• Desarrollados para Python, admiten varios lenguajes de programación

  • Quarto puede incluir celdas de código en otros lenguajes, incluido Python

• Se crean, visualizan y ejecutan solo en navegadores web, aunque son fácilmente modificables, en su entorno de trabajo

  • con una instalación local (usando Python) u online en JupyterLab (y también incluye un tipo de dashboard propio: Voilà)

  • o con Google Colab, también para R

• Quarto renderiza libros de Jupyter, creados en .qmd o en su propio formato

• Muchas herramientas están preparadas para Python y R porque se usan a menudo indistintamente o combinados